\chapter{MDParser User's Manual}

MDParser is the tool that implements the techniques to extract RTL patterns from MD files as explained in our thesis. This section describes the system requirements and some
examples to show the usage of the tool.

\section{System Requirements}

The tool has been successfully tested under the following conditions. The tool is expected to work in any compatible systems.

\begin{itemize}
 \item \emph{Processor:} Intel Core i3.
 \item \emph{OS:} Ubuntu 10.04 LTS.
 \item \emph{Compiler:} gcc version 4.4.3 (Ubuntu 4.4.3-4ubuntu5.1), used for building the tool.
 \item \emph{MD Files Used:} MD files are taken from the back-end of GCC version 4.6.1.
 \item \emph{Compiler Tools:} flex 2.5.35, bison (GNU Bison) 2.4.1., GNU Make 3.81.
\end{itemize}


\section{Installation}
A make file is provided along with the source of MDParser. The tool can be built using this make file by giving the following command at the root
of the source tree,

make

The tool will be built and stored as a binary executable file bin/md\_parser. The compiled binary can be moved to any directory.

\section{Options}
The following are the options supported by the tool.


\begin{enumerate}
 \item parse
 \item output
 \item graph
 \item include
 \item param
 \item expand
 \item split
 \item dir
 \item intersect
 \end{enumerate}



\subsection{parse} 

This option parses the MD files and generate patterns.

The argument is a directory name. For example, to parse mips.md, mips.md should be in directory mips. As argument, give the full path to mips without any trailing '/' 
character.

Example :

bin/md\_parser -parse test/mips

the above command starts parsing mips.md in ./test/mips/mips.md


Use the option output along with it to specify the file to which it has to be output

bin/md\_parse -parse test/mips -output mips.mi

will write output to file mips.mi. If output is not set, default option is to print it to stdout.


\section{Patterns in dot Format}

We added the functionality to print each of the patterns in the pattern list in the dot format, which can be used by
the tool graphviz\cite{dot}. This tool helps in visually representing graphs. 
By writing patterns this way, the output file can be compiled
using the dot tool to get a graphical representation of each of the patterns in the patterns list as seen in the examples above. This helps understanding the
patterns easier. 

Use the option graph to print the patterns in dot format.

bin/md\_parser - parse test/mips -output mips.mi -graph mips.dot

The above command will list the patterns in dot notation in the file mips.dot apart from writing patterns to mips.mi. The mips.dot file can be further compiled using
the dot tool to get the graphical representation of the patterns, with each pattern listed in one page.

\subsection{intersect}
This option, given two pattern files, lists the patterns that are common to both the files.

\begin{itemize}
 \item This option expects two mi files which are list of patterns generated by parse command separated by commas(no spaces).
 \item Copy the code\_iterators listed in first file to second file and remove code iterators from first file.
 \item If two code\_iterators are found to be equivalent, but have different names, use ``find and replace'' to make both the code iterators have the same 
name and the same name is used in patterns.
\end{itemize}

A sample usage scenario is,

bin/md\_parse -intersect mips.mi,arm.mi -output mips-arm.mi


\subsection{split} 
This option splits an MD file into two files, one containing pattern index in place of RTL templates and another containing the corresponding parameters for the template.
This option can also be made to output a single file containing the pattern index and its parameter together.

Example :
bin/md\_parse -split test/mips -include mips.mi -dir mips-output

\begin{itemize}
 \item split expects a directory as in the case of parse command as an argument. This command will start parsing from test/mips/mips.md.
 \item -include tells the pattern file(mips.mi) to look up. This has to be generated by the parse command.
 \item -dir command tells the directory in which the output files will be generated. Say, for a file mips.md, mips.com and mips.par will be generated.
mips.com contains instructions in compressed form, templates will be given by index of pattern in mi file. mips.par will contain parameters.
   
\end{itemize}


\subsection{expand}

This option, combines the pattern index and parameters and produces the RTL templates back to get the MD files in the format supported by GCC. This option was tested by 
generating first splitting MD files to patterns and parameters using the split command and then regenerating the MD files back.

bin/md\_parse -expand mips-output/mips.com -include mips.mi -param mips-output/mips.par -dir mips-output1

\begin{itemize}
 \item expand option expects the base .com file which \emph{include}s all other .com files. for mips machine it will be mips.com.
 \item include must be used with -expand as is the case with split option.  
 \item param tells the base file which \emph{include}s parameters for all .com files.
 \item dir tells the directory in which the output files has to be written.  
\end{itemize}

All corresponding com and par files will be merged to get the .md files back. Example, mips.com and mips.par will be merged to get mips.md in mips-output1
directory.

























